Receiving Streaming Movies

Opening A Streaming Movie

In general, opening a streaming movie is like opening any QuickTime movie. You can open a streaming movie by opening

a movie file that contains streaming tracks
an SDP file
a URL

You can open a movie file that contains streaming tracks, or open an SDP file, by calling NewMovieFromFile in the usual way.

You open a movie from a URL by calling NewMovieFromDataRef with a URL data reference. The URL for a real-time streaming movie will use RTSP:// protocol. The following is a code sample for opening a movie from an RTSP URL:



 
char url[] = "rtsp://www.mycompany.com/mymovie.mov";

Handle urlDataRef;



 
urlDataRef = NewHandle(strlen(url) + 1);

if ( ( err = MemError()) != noErr) goto bail;



 
BlockMoveData(url, *urlDataRef, strlen(url) + 1);



 
err = NewMovieFromDataRef(&movieInfo->theMovie, newMovieActive,

    nil, urlDataRef, URLDataHandlerSubType);

DisposeHandle(urlDataRef);

It's also possible to open a movie file from an HTTP:// or FTP:// URL, and for that movie file to contain streaming tracks.

If you open a streaming movie from a URL or an SDP file, the Movie Toolbox will call the appropriate movie importer. If you open a movie file that contains streaming tracks, stream importers will be called.

Figure 6 Opening a streaming movie

Opening a streaming movie typically takes more time than opening a movie with purely local content. Each track in the movie on the server is transmitted as an RTP stream, so the client computer must establish a network connection with the server for each track, and often must establish a connection for RTSP control as well. This takes time, particularly if a dial-up connection must be established.

It also means the Movie Toolbox can return connection status messages or networking errors in the process of opening a movie.

Playing A Streaming Movie

Applications that can already play QuickTime movies need to take the following steps to play real-time streaming movies reliably:

Open movies with high-level Movie Toolbox calls or a movie importer.
Do not assume that the track structure of the movie you play reflects the track structure of the original movie; a streaming track can contain sound, video, text, MIDI, or all of these.
Use a movie controller to play the movie, or use the new PrePrerollMovie function to set up any streams before playing the movie.
Display status messages returned by the movie controller.
Be prepared to deal with network errors when your application plays a movie (see "Common Streaming Error Codes" ).
Be prepared for movie characteristics to change dynamically; the height, width, duration, and whether or not the movie has audio or video can all change as the movie plays.
Do not assume that the movie will begin immediately.

The following sections describe some of these steps in more detail.

Track Structure

Unlike other QuickTime movies, streaming movies consist of two distinct movie files--one on the server and the other on the client machine--often with different track structures. You sometimes need to distinguish between the server movie and the client movie .

The media of each track in the server movie is transmitted as a separate RTP stream. On the client side, multiple RTP streams can be combined into a single streaming track.

If you open a movie from a URL, for example, the movie importer may create a client movie that contains only a streaming ('strm' ) track. Unlike most other QuickTime track types, a streaming track can contain multiple media streams of different types. A streaming track in a client movie may contain the URL of a server movie with audio, video, text, and/or MIDI tracks.

Figure 7 Server movie and client movie

The client movie file never contains audio or video media from the server movie; they are displayed and discarded. If a client movie is saved, the saved movie contains information such as the URL of the server movie and the currently-displayed movie time. The client movie can also contain local tracks and local media, but the media samples in the server movie remain on the server except when playing.

Pre-Prerolling

Before any movie is played, QuickTime needs to allocate buffers and open appropriate media handlers. This process is called prerolling the movie. Before a streaming movie can be played, additional steps need to be taken, such as establishing RTP streams between the client and the server. This setup process is called pre-prerolling . Pre-prerolling is performed automatically when a streaming movie is played using a movie controller. If your application uses movie controllers to play movies, you do not need to take any special steps to pre-preroll a streaming movie.

If you are playing movies using lower-level commands, you will need to use the new PrePrerollMovie function to set up the network connections for a streaming movie before you can preroll or play the movie. The PrePrerollMovie function does nothing unless a movie contains streaming content, so it's safe to call it for all movies. A code sample follows.



 
    PrePrerollMovie(myMovie, 0, GetMoviePreferredRate(myMovie),

    NewMoviePrePrerollCompleteProc(MyMoviePrePrerollCompleteProc), 

    (void *)0L);

PrePrerollMovie operates either synchronously or asynchronously, depending on whether you specify a completion procedure when you call it.

If called asynchronously, it returns almost immediately, even if the movie contains streaming content. This allows your application to perform other tasks while awaiting the completion of the pre-prerolling. You need to call MoviesTask periodically to grant time for the task of pre-prerolling when using it asynchronously.

When the pre-prerolling is finished, PrePrerollMovie calls the completion procedure whose address you pass in the NewMoviePrePrerollCompleteProc parameter. In the simplest case, the completion procedure will want to preroll and start the movie.

If no completion procedure is specified, PrePrerollMovie returns when the pre-preroll process is complete

Reacting to Changes in Movie Characteristics

One feature of streamed movies is that their characteristics may change dynamically during playback. For example, when you open a movie from a URL you may not know the actual height and width of the movie, its duration, how many streams it contains, whether it has a sound track, or whether it is an audio-only movie.

QuickTime will assign default values to these characteristics if they are unknown. QuickTime can notify your application when the movie characteristics become known or are changed.

In most cases, your application will want to adjust the size of the window or pane that contains the movie to reflect such changes. You make these adjustments by implementing a movie controller action filter proc.

To do this, you first need to indicate to the Movie Toolbox that you want to be informed of any changes. You do this by setting a movie playback hint:



 
SetMoviePlayHints(myMovie, hintsAllowDynamicResize,

        hintsAllowDynamicResize);

Changes in the movie size are announced to your filter proc by the mcActionControllerSizeChanged selector. Changes in other movie characteristics are announced through the mcActionMovieEdited selector.

Size Changes

Whenever the size of the movie changes, the associated movie controller sends the mcActionControllerSizeChanged action to your movie controller action filter procedure. You can intercept that action and respond to it as follows:



 
pascal Boolean MyMCActionFilterProc (MovieController theMC, short theAction, void *theParams, 

long theRefCon)



{

    Movie   myMovie = MCGetMovie(theMC);



        switch (theAction) {

            // handle window resizing

            case mcActionControllerSizeChanged:

                MyResizeWindow(myMovie);

                break;



            default:

                break;

        }



        return(false);

}

Duration Changes

The duration of a streaming movie or a streaming track may not be initially known. A track or movie whose duration is not known is assigned an indefinite duration : x7FFFFFF . If you do not treat this as a special case, a streaming movie will appear to your application as a very long movie indeed.

Once the pre-preroll process is complete, QuickTime should know the actual duration of the streams. If you set an action filter proc and call SetMoviePlayHints , your application will be called with the mcActionMovieEdited selector when QuickTime determines the actual duration.

If the movie contains live content, it may not have a specific duration. In this case, the duration remains indefinite: x7FFFFFF . You might want to set a timeout in your code that detects the fact that QuickTime has not adjusted the duration from x7FFFFFF after a few seconds of movie play. QuickTimePlayer uses such a timeout and displays a "Live Transmission" message where the slider would be for a movie with a known duration.

Sound and Video Changes

Whether a streaming movie has sound ('ears' ) or is sound-only (no video) may not be initially known or may change dynamically. If you set an action filter proc and call SetMoviePlayHints , your application will be called with the mcActionMovieEdited selector when the sound or video characteristics change.

Other Playback Considerations

Streaming movies only play back at a rate of 1 . Other playback rates, such as playing backward, are not supported.